Design System Consumption & Source-of-Truth Plan · v2 · reconciled July 30, 2026

PTR Design Kit

Making the design system the company's source of truth

A plan to ingest the PTR Design Kit into the Priority Hub app and standardize it as the de-facto system across every PTR surface — with one versioned package as the single source of truth, and the brand/deck assets kept fully usable outside the app. Phase 1 is closed: v0.2.0 tagged July 22, and distribution moved the same day to jsDelivr off the public repo — no registry, no auth; the files serve, and Phase 2 (the Priority Hub app swap) is next.

The core insight

The Priority Hub app and this design system already speak the same language. The app is built on Tailwind v4 + the DaisyUI plugin (input.css → output.css), and its live theme is declared in og_dashboard.css as [data-theme="light"] / [data-theme="dark"] blocks. Those blocks set the exact same CSS variables our ptr-theme.css defines — --color-primary, --color-base-100, --radius-box, and so on. Today they hold an Apple-style blue palette (#0071e3); our theme holds PTR Green (#086033).

The source-of-truth chain

One directional flow, no parallel copies. Figma is where design decisions are made; a single published package is what everything installs. Nothing hand-maintains a second copy of the tokens.

Governance — how it stays the source of truth

• One edit path. Token changes start in Figma, land in PTR.tokens.json via export, and are released by bumping the package version. No consumer ever hand-edits token values.
• Semantic versioning. Patch = value tweak, minor = new token/component, major = a rename or removal. Consumers pin a version and upgrade deliberately.
• Ownership. Design owns the Figma theme; the package release is a small, reviewable PR. The audit doc (AUDIT_PLAN.md) tracks the remaining backlog.
• The anti-drift guarantee holds. The @plugin "daisyui/theme" block and the runtime [data-theme] CSS are both generated from PTR.tokens.json — never edited by hand in two places — closing audit item #1 (two parallel systems that drift the moment a token changes) permanently. And because component CSS references tokens and never hardcodes values, a single package bump re-skins every surface at once — which is exactly what makes it a real source of truth rather than a style guide people ignore.

The package: one package, everything in it

Per your call, we ship a single scoped package and let each consumer link only the layer it needs. Served from the public design-kit repo via jsDelivr — no registry, no auth anywhere; every consumer pins a v* tag in the URL. (Revised July 22: GitHub Packages dropped before any consumer installed.)

// package.json "exports" — consumers cherry-pick their layer
{
  "./theme.css":      // DaisyUI "PTR" theme — the tokens the app needs
  "./theme.plugin.css": // @plugin block for Tailwind+DaisyUI builds
  "./theme-dark.css":  // NEW (July 16) — branded dark theme, selector-gated (D5)
  "./brand.css":      // extensions: brand palette, case-status, type scale
  "./marketing.css"   // + "./pages.css" — marketing/web layer, canonical July 17
  "./product.css":    // shared product layer — shipped in v0.2 (July 17)
  "./tokens.json":    // + "./tokens.dark.json" — the source-of-truth token sets
  "./assets/*"         // logo lockups, textures, fonts config
}

Integrating into the Priority Hub app

You chose to replace the app's light / dark theme values with PTR — which means zero changes to templates or JavaScript. The Alpine binding :data-theme="darkMode ? 'dark' : 'light'" stays exactly as it is; we only change what those two theme names resolve to.

1. Link the package

   No install — three tag-pinned jsDelivr <link>s in the base template, after the compiled output.css: theme.css, brand.css, theme-dark.css.

2. Leave input.css alone

   @plugin "daisyui" { themes: light, dark } stays — the built-ins remain registered as a fallback. Loading after output.css, theme.css overrides light to PTR and theme-dark.css re-flips dark to the branded dark. Theme names unchanged, so the Alpine binding is untouched.

3. Delete the app's inline palette overrides

   Remove the [data-theme="light"] / [data-theme="dark"] variable blocks from og_dashboard.css. They become redundant — the package now owns those values. All the app-specific component rules below them stay untouched.

4. Fonts (+ brand layer already linked)

   brand.css ships in the step-1 link stack, so case-status colors and the type scale are available app-wide. Swap the Google Fonts <link> for the package's font config to guarantee the exact Inter weights.

5. Rebuild & verify

   npm run build:css. The dashboard renders in PTR Green with no template edits. Spot-check contrast on badges and the leaderboard (audit item #8).

<link rel="stylesheet" href="{% static 'css/output.css' %}">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/PriorityTaxRelief-Development/design-kit@v0.2.0/package/theme.css">       // PTR tokens → override "light"
<link rel="stylesheet" href="…/design-kit@v0.2.0/package/brand.css">       // extension tokens + .ptr-* classes
<link rel="stylesheet" href="…/design-kit@v0.2.0/package/theme-dark.css">  // branded dark → re-flips "dark"

[data-theme="light"] { --color-primary: #0071e3; --color-base-100: #fff; … }
[data-theme="dark"]  { --color-primary: #2997ff; … }
/* ✓ keep: .og-sidebar, .og-lb-card, .dispo-chip, all component rules —
   they read var(--color-*) and now inherit PTR automatically */

Consumption playbook — every other surface

Same package, same entry point everywhere: tag-pinned jsDelivr links — identical URLs whether or not the platform can run a build (jsDelivr auto-serves minified .min.css variants). Repos that want the theme registered at build time vendor theme.plugin.css from the tagged URL. The brand/deck side stays independent by design: it consumes only brand.css (palette, type, logos, textures) and the standalone slides/ templates — never the DaisyUI component layer — so a product CSS change can never break a slide, and a deck asset can never leak into the product bundle. One source of truth, two clean audiences.

Marketing layer — discrepancy & open-issues log

Audit of the Services project (July 15, 2026) against the system: token coverage is solid — its ptr-tokens.css matches the package exactly, and both site stylesheets use zero hardcoded brand hex. But the site made five design decisions the system doesn't cover. They were ingested verbatim into ui_kits/marketing/ and logged here — decided & executed July 16, 2026. This log now also tracks the audit's open items (#). Resolved rows are grayed; open rows need your call.

Rollout in three phases

Worklog — Phase 1

Running record of the build-out, updated as steps land. Last update July 22, 2026. Phase 1 closed with the July 22 release.

• Package scaffold — package/ with package.json: exports map, files list, semver scripts (the publishConfig came out on July 22 with the jsDelivr switch). Docs in package/README.md.
• Token build — build.mjs generates theme.css, theme.plugin.css and the @generated block in brand.css from tokens.json; --check runs in CI on every v* tag, so a stale file fails the release. The anti-drift rule is now enforced, not aspirational.
• brand.css extension layer — palette, case-status, type scale as .ptr-* classes, spacing, shadows; new motion tokens (--duration-*, --ease-*) close audit #13. Tokens + classes only — safe to load app-wide.
• Assets — 11 logo lockups in package/assets/logo/; grain texture compressed 7.9 MB → 116 KB grain.jpg (audit #6). Full-res master stays repo-only.
• Repo eats its own package — ptr-theme.css re-exports package/theme.css; colors_and_type.css imports package/brand.css and keeps only preview element defaults. No second copy of any token remains.
• Bundle hygiene (audit #2/#5) — StatusBadge extracted to its own component with a declared .d.ts dependency; demo fixtures now module-local, off window and the namespace; CaseList takes an optional cases prop. Publish-blocker cleared.
• Inventory & hygiene pass — every root file bucketed (see inventory below); uploads/ removed: the tokens JSON now lives canonically at package/tokens.json, and Group 130.svg duplicated ptr-flag-black.svg.
• Logo dedup — assets/logo/ deleted (11 SVGs were byte-identical to package/assets/logo/ with no sync check); every reference (previews, slides, product kit, templates, docs) repointed at the package copy. One copy, zero drift.
• GH Pages guideline site — root index.html renders the README content + all 30 preview cards + 8 slides as a navigable brand-guideline page; .nojekyll added so _ds_* files serve correctly on GitHub Pages.
• Official logo kit consumed — pulled from PriorityTaxRelief-Development/ptr_logo (closes the "Figma-lifted logos" caveat): 4 vector masters ship in the package at assets/logo-kit/svg/; high-res PNGs (Horz 4800, Stacked 4800, Icon 2400), favicon set, BIMI and social covers stay repo-only in assets/logo-kit/ to keep npm lean. New Downloads section on index.html.
• Marketing layer ingested — Services-site audit passed (token parity exact, zero hardcoded hex); site.css + pages.css pulled verbatim into ui_kits/marketing/ (dev-only preview switcher stripped) with README, specimen card, and the D1–D5 discrepancy log above. Behaviors stay site-side by design.
• Discrepancy decisions D1–D5 executed (July 16) — marketing type on the system scale (body → --fs-body, weight-400 headings with token-capped clamps); eyebrows converged on Inter as quiet + loud variants in brand.css; layout tokens (--site-max/--gutter/--header-h) promoted; all 77 transitions on the --duration/--ease-out tokens; dark mode promoted to package/theme-dark.css with new --surface-1/2 tokens (closes audit #12). Five outliers O1–O5 logged above.
• Post-reconciliation verification (July 16) — zero var(--ease)/literal-duration transitions left in the marketing layer; every referenced token (--fs/--lh/--ls/--surface/--duration/--ease) resolves in brand.css; undefined --text-1/--border-1 refs eliminated; theme-dark.css wired into the package exports map, files list, and the repo preview chain (colors_and_type.css); eyebrow specimen card updated. Design-system compile clean.
• Outliers O1–O5 executed (July 16) — .ptr-title (weight-800 component titles, --fs-title 21) + web-copy mid tokens --fs-lead-web/--fs-intro/--fs-body-lg consumed across the marketing layer; display line-height tokens re-expressed unitless (deck output unchanged); entrance reveal on --duration-slow — zero literal durations remain; tokens.json gains brand/surface/layout groups with a new tokens.dark.json dark mode, and build.mjs now generates theme-dark.css — the JSON pair is ready for the Figma-side import.
• #8 orange rule + branded-dark adoption (July 16) — orange codified as a selective accent (never small text · big display headlines OK · CTA fill with dark text only; documented in brand.css): loud eyebrows + card/post links + hover links → green (bright variant in dark mode), form-error micro-text → the DaisyUI error pair. App plan now points the dark theme name at theme-dark.css — the neutral dark placeholder is dropped.
• Product surface Phase 1 shipped (July 17) — Django codebase linked and reviewed; ui_kits/product/reference.html + reference.css deliver the componentized Inbox + Case Detail specimen (.tp-* contract, both status taxonomies as 8 tint/ink groups, Django partial map + HTMX seams matched to their conventions). The custom-CSS budget (DaisyUI first · 2+ apps → package · bespoke reads tokens, never hex) is codified in the Product Surface Plan and scopes product.css for v0.2.
• Marketing layer packaged (July 17) — canonical marketing.css + pages.css moved into package/ (vocabulary only; token layers load first), wired into the exports map + files; ui_kits/marketing/ now re-exports the package copies — same no-second-copy pattern as ptr-theme.css.
• product.css layer — v0.2 shipped (July 17) — the shared product layer is live: package/product.css carries status pills (.tp-pill--{group}), empty state, filter bar and toast, tokens only; the 8 --case-{group}-bg/-fg tint/ink pairs promoted into brand.css (hand-authored block, badge-tint rule, Figma re-export pending); wired into the exports map + files, version bumped to 0.2.0.
• First release — shipped (July 22) — repo pushed to PriorityTaxRelief-Development/design-kit; CI release workflow added (.github/workflows/publish.yml: fires on v* tags, staleness check, tag-vs-version guard, publishes with the built-in GITHUB_TOKEN — no PAT). Package renamed @prioritytaxrelief-development/design-kit (scope must match the org owner — the original @prioritytaxrelief scope 403'd). v0.2.0 is live on GitHub Packages.
• Distribution switched to jsDelivr (July 22) — GitHub Packages dropped before any consumer installed. The design-kit repo is public; consumers link tag-pinned cdn.jsdelivr.net/gh/…/package/* URLs — no .npmrc, no token. publishConfig removed and the package marked "private": true (guards against accidental registry publishes); publish.yml reduced to a tag check (staleness + tag-vs-version — the tag is the release); theme.plugin.css becomes vendor-only (a build-time @plugin block can't load from a CDN) — the Phase-2 app swap consumes the runtime files via <link> instead. Handoff, package README and this plan repointed.
• Product surface Phase 2 — normalization (July 17) — .tp-* collapsed onto DaisyUI per the specimen's §7 map: buttons/fields/checkboxes are DaisyUI classes (previewed via ui_kits/product/daisy.css, a preview-only shim), 2px field/button borders, 4/4/8 radii, primary focus, PTR type scale (12/14/16 + tabular numerals; 10px overline kept as a local --fs-micro alias — candidate token), --space-*/--shadow-*/duration tokens throughout. The interactive kit adopted the surviving .tp-* names and app.js color maps now emit token/group references, not hex — the working-25 grouping stays one re-mappable table (WORKING_GROUP, matches the specimen §1) pending E-001.7.
• Product surface — responsive shell (July 17) — post-normalization pass: ≤1240px case-row grid restructured (no id/checkbox overlap), ≤880px sidebar becomes a hamburger-triggered drawer (logo/brand + Plan notes drop, search fills the header; search width cap removed globally). Shell-only classes, specimen contract unchanged.
• E-001.7 — filter side reconciled (July 17) — inbox STATUS filter switched to the finalized-17 (the Case Detail list), matching a case when any year × return × jurisdiction status equals the pick; specimen + plan notes updated. Same day, the display side: the Overall TP pill (rows + Case Detail + reports) now maps the Logics working value through WORKING_TO_FINAL — one re-mappable 25→17 table, raw value in the tooltip. Remaining: business sign-off on the mapping.
• Product surface Phase 3 — forms → Django spec (July 17) — the three tracking modals shipped as server-rendered form specs: ui_kits/product/forms.html (§8) carries per-form field tables (types, required, conditional-on, error copy verbatim from app.js), copy-paste modal markup on DaisyUI modal + native <dialog>, and the HTMX contract (open as fragment → #tp-modal + showModal(), delayed inline validation, submit → close + toast + owning-region swap; bookkeeping points recompute server-side — BK_PTS weights backend-configured). The §7 modal collapse applied: daisy.css gained the modal/modal-box/modal-backdrop shim and the interactive kit's three modals now run on <dialog> — app.js business logic untouched, wiring only. Suggested partials: _tracking_form / _handpull_form / _bk_form / _form_field / _bk_points_bar.
• Documentation reconciliation (July 30) — the three living docs had drifted apart, so they were re-aligned and de-duplicated. Corrected here: the exports map (product.css shipped in v0.2, pages.css + tokens.dark.json listed), the stale publishConfig/prepublishOnly and "v0.1.0 is publish-ready" lines, card counts (28 preview / 40 registered), and worklog chronology. Duplication removed: design_handoff_phase2_app_swap/reference/ held second copies of theme.css, brand.css, theme-dark.css, both token JSONs and the package README — deleted in favor of tag-pinned jsDelivr URLs, since a stale token copy inside the handoff is exactly the drift this plan's anti-drift guarantee promises can't happen; and ui_kits/product/base.css now holds the import stack + :root alias block that product.css and reference.css each carried a byte-identical copy of. AUDIT_PLAN.md gains a Remaining backlog section (items 4, 10, 14, 15, 16) so open work lives in exactly one place.
• Audit #4 + #16 closed (July 30) — contrast: every sanctioned pairing measured and written down (README Accessibility & contrast — text · fills · status rules; two cards (text & fills · status & dark) recompute each ratio from the live tokens through a shared preview/contrast-ledger.js, so they can't go stale; summary in brand.css). Findings: text stays on ink/graphite/base-400/green, orange fills always carry dark text, status text uses the --case-* pairs (all eight clear AA), and on dark --ptr-green-bright replaces --color-primary (2.38:1). Two exported feedback pairs miss AA for normal text → item 17, a Figma-side token edit. Changelog: package/CHANGELOG.md reconstructs 0.1.0 / 0.2.0 from this worklog and ships in the package, so a consumer pinning a tag can see what a bump brings; writing the entry is now part of the release recipe.

Repo inventory — what lives where

Four buckets. Only package/ ships to consumers; everything else either powers this workspace or documents the work. Audited July 15, 2026 — nothing unaccounted for remains at root.